---
title: 'Quickstart'
description: 'Start using OASIS for social simulations in under 5 minutes'
---

## Setup your environment

Learn how to set up OASIS and run your first social simulation.

### Installation
You can install OASIS in two ways:

<AccordionGroup>
  <Accordion icon="download" title="Option 1: Install via pip">
    ```bash
    pip install camel-oasis
    ```
  </Accordion>
  <Accordion icon="github" title="Option 2: Clone the repository">
    ```bash
    git clone https://github.com/camel-ai/oasis.git
    cd oasis

    pip install --upgrade pip setuptools
    pip install -e . # This will install dependencies as specified in pyproject.toml
    ```
  </Accordion>
</AccordionGroup>

## Running simulations

OASIS supports different types of LLM backends for running simulations. Choose the option that works best for your needs.

### Using OpenAI API

<AccordionGroup>
  <Accordion icon="key" title="Set up your API key">
    Add your OpenAI API key to your environment variables:

    **For Bash (Linux, macOS, Git Bash on Windows):**
    ```bash
    export OPENAI_API_KEY=<insert your OpenAI API key>
    export OPENAI_API_BASE_URL=<insert your OpenAI API BASE URL>  # Optional: for proxy services
    ```

    **For Windows Command Prompt:**
    ```bash
    set OPENAI_API_KEY=<insert your OpenAI API key>
    set OPENAI_API_BASE_URL=<insert your OpenAI API BASE URL>  # Optional: for proxy services
    ```

    **For Windows PowerShell:**
    ```bash
    $env:OPENAI_API_KEY="<insert your OpenAI API key>"
    $env:OPENAI_API_BASE_URL="<insert your OpenAI API BASE URL>"  # Optional: for proxy services
    ```
  </Accordion>
  <Accordion icon="face-smile" title="Prepare the user profiles">
    If you install with `pip`, download [this file](https://github.com/camel-ai/oasis/blob/main/data/reddit/user_data_36.json) to your own `./data/reddit/user_data_36.json` directory.
  </Accordion>
  <Accordion icon="play" title="Run a Reddit simulation">
    Execute the Reddit simulation script:
    ```python
    import asyncio
    import os

    from camel.models import ModelFactory
    from camel.types import ModelPlatformType, ModelType

    import oasis
    from oasis import (ActionType, LLMAction, ManualAction,
                      generate_reddit_agent_graph)


    async def main():
        # Define the model for the agents
        openai_model = ModelFactory.create(
            model_platform=ModelPlatformType.OPENAI,
            model_type=ModelType.GPT_4O_MINI,
        )

        # Define the available actions for the agents
        available_actions = [
            ActionType.LIKE_POST,
            ActionType.DISLIKE_POST,
            ActionType.CREATE_POST,
            ActionType.CREATE_COMMENT,
            ActionType.LIKE_COMMENT,
            ActionType.DISLIKE_COMMENT,
            ActionType.SEARCH_POSTS,
            ActionType.SEARCH_USER,
            ActionType.TREND,
            ActionType.REFRESH,
            ActionType.DO_NOTHING,
            ActionType.FOLLOW,
            ActionType.MUTE,
        ]

        agent_graph = await generate_reddit_agent_graph(
            profile_path="./data/reddit/user_data_36.json",
            model=openai_model,
            available_actions=available_actions,
        )

        # Define the path to the database
        db_path = "./data/reddit_simulation.db"

        # Delete the old database
        if os.path.exists(db_path):
            os.remove(db_path)

        # Make the environment
        env = oasis.make(
            agent_graph=agent_graph,
            platform=oasis.DefaultPlatformType.REDDIT,
            database_path=db_path,
        )

        # Run the environment
        await env.reset()

        actions_1 = {}
        actions_1[env.agent_graph.get_agent(0)] = [
            ManualAction(action_type=ActionType.CREATE_POST,
                        action_args={"content": "Hello, world!"}),
            ManualAction(action_type=ActionType.CREATE_COMMENT,
                        action_args={
                            "post_id": "1",
                            "content": "Welcome to the OASIS World!"
                        })
        ]
        actions_1[env.agent_graph.get_agent(1)] = ManualAction(
            action_type=ActionType.CREATE_COMMENT,
            action_args={
                "post_id": "1",
                "content": "I like the OASIS world."
            })
        await env.step(actions_1)

        actions_2 = {
            agent: LLMAction()
            for _, agent in env.agent_graph.get_agents()
        }

        # Perform the actions
        await env.step(actions_2)

        # Close the environment
        await env.close()


    if __name__ == "__main__":
        asyncio.run(main())
    ```
    This will start a simulation of user interactions in a Reddit-like environment.
  </Accordion>
</AccordionGroup>

### Using local open-source models with VLLM

<AccordionGroup>
  <Accordion icon="server" title="Set up VLLM">
    1. Install VLLM by following the instructions in the [VLLM repository](https://github.com/vllm-project/vllm)

    2. Download a model (e.g., Qwen 2.5) to your local machine:
    ```bash
    pip install huggingface_hub

    huggingface-cli download --resume-download "Qwen/Qwen2.5-7B-Instruct" \
      --local-dir "YOUR_LOCAL_MODEL_DIRECTORY" \
      --local-dir-use-symlinks False \
      --resume-download \
      --token "YOUR_HUGGING_FACE_TOKEN"
    ```

    3. Deploy the VLLM API server:
    ```bash
    vllm serve /path/to/Qwen2.5-7B-Instruct --host 0.0.0.0 --port 8000 \
      --served-model-name 'qwen-2' \
      --enable-auto-tool-choice \
      --tool-call-parser hermes
    ```

    4. Test if VLLM is correctly deployed:
    ```bash
    curl http://$ip:$port/v1/models
    ```
  </Accordion>
  <Accordion icon="play" title="Run a Twitter simulation with local models">
    1. Edit or write the `scripts/environment/twitter_simulation.py` file to use your VLLM deployment:
    ```python
    vllm_model_1 = ModelFactory.create(
        model_platform=ModelPlatformType.VLLM,
        model_type="qwen-2",
        url="http://$ip:$port",
    )
    vllm_model_2 = ModelFactory.create(
        model_platform=ModelPlatformType.VLLM,
        model_type="qwen-2",
        url="http://$ip:$port",
    )
    models = [vllm_model_1, vllm_model_2]
    ```
    2. Prepare the user profiles:
    If you install with `pip`, download [this file](https://github.com/camel-ai/oasis/blob/refactor/data/twitter_dataset/anonymous_topic_200_1h/False_Business_0.csv) to your own `data/twitter_dataset/anonymous_topic_200_1h/False_Business_0.csv` directory.
    3. Run the Twitter simulation:
    ```python
    import asyncio
    import os

    from camel.models import ModelFactory
    from camel.types import ModelPlatformType

    import oasis
    from oasis import (ActionType, LLMAction, ManualAction,
                      generate_twitter_agent_graph)

    async def main():
        # Define the models for agents. Agents will select models based on
        # pre-defined scheduling strategies
        vllm_model_1 = ModelFactory.create(
            model_platform=ModelPlatformType.VLLM,
            model_type="qwen-2",
            url="http://$ip:$port",
        )
        vllm_model_2 = ModelFactory.create(
            model_platform=ModelPlatformType.VLLM,
            model_type="qwen-2",
            url="http://$ip:$port",
        )
        models = [vllm_model_1, vllm_model_2]

        # Define the available actions for the agents
        available_actions = [
            ActionType.CREATE_POST,
            ActionType.LIKE_POST,
            ActionType.REPOST,
            ActionType.FOLLOW,
            ActionType.DO_NOTHING,
            ActionType.QUOTE_POST,
        ]

        agent_graph = await generate_twitter_agent_graph(
            profile_path="./data/reddit/user_data_36.json",
            model=models,
            available_actions=available_actions,
        )

        # Define the path to the database
        db_path = "./data/twitter_simulation.db"

        # Delete the old database
        if os.path.exists(db_path):
            os.remove(db_path)

        # Make the environment
        env = oasis.make(
            agent_graph=agent_graph,
            platform=oasis.DefaultPlatformType.TWITTER,
            database_path=db_path,
        )

        # Run the environment
        await env.reset()

        actions_1 = {}

        actions_1[env.agent_graph.get_agent(0)] = ManualAction(
            action_type=ActionType.CREATE_POST,
            action_args={"content": "Earth is flat."})
        await env.step(actions_1)

        actions_2 = {
            agent: LLMAction()
            # Activate 5 agents with id 1, 3, 5, 7, 9
            for _, agent in env.agent_graph.get_agents([1, 3, 5, 7, 9])
        }

        await env.step(actions_2)

        actions_3 = {}

        actions_3[env.agent_graph.get_agent(1)] = ManualAction(
            action_type=ActionType.CREATE_POST,
            action_args={"content": "Earth is not flat."})
        await env.step(actions_3)

        actions_4 = {
            agent: LLMAction()
            # get all agents
            for _, agent in env.agent_graph.get_agents()
        }
        await env.step(actions_4)

        # Close the environment
        await env.close()


    if __name__ == "__main__":
        asyncio.run(main())
    ```
  </Accordion>
</AccordionGroup>
